Creating Dialog Boxes

The following Dialog Manager functions for creating dialog boxes are new, changed, or not recommended with Appearance Manager 1.0:

GetNewDialog

Creates a dialog box from a resource-based description.



 
pascal DialogPtr GetNewDialog (

                     short dialogID,

                     void *dStorage,

                     WindowPtr behind);

dialogID: The resource ID of a dialog resource and an extended dialog resource. The resource IDs for both resources must be identical. If the dialog resource is missing, the Dialog Manager returns to your application without creating the requested dialog box. See 'DLOG' and 'dlgx' for a description of the dialog resource and the extended dialog resource, respectively.
dStorage: A pointer to the memory for the dialog structure. If you set this parameter to nil , the Dialog Manager automatically allocates a nonrelocatable block in your application heap.
behind: A pointer to the window behind which the dialog box is to be placed on the desktop. Set this parameter to the window pointer (WindowPtr)-1L to bring the dialog box in front of all other windows.
function result: Returns a pointer to a dialog box. If none was created, returns nil .

DISCUSSION

The GetNewDialog function creates a dialog structure from information in a dialog resource and an extended dialog resource (if it exists) and returns a pointer to the dialog structure. You can use this pointer with Window Manager or QuickDraw functions to manipulate the dialog box. If the dialog resource specifies that the dialog box should be visible, the dialog box is displayed. If the dialog resource specifies that the dialog box should initially be invisible, use the Window Manager function ShowWindow to display the dialog box.

The dialog resource contains a resource ID that specifies both the dialog box's item list ('DITL') resource and its dialog font table ('dftb') resource. After calling the Resource Manager to read these resources into memory (if they are not already in memory), GetNewDialog makes a copy of the 'DITL' resource and uses that copy; thus you may have several dialog boxes with identical items.

If you supply a dialog color table ('dctb') resource with the same resource ID as the dialog resource, GetNewDialog uses NewColorDialog and returns a pointer to a color graphics port. If no dialog color table resource is present, GetNewDialog uses NewDialog to return a pointer to a black-and-white graphics port, although system software draws the window frame using the system's default colors. However, if the Appearance Manager is available and the kDialogFlagsUseThemeBackground feature bit of the extended dialog resource is set, then the 'dctb' resource is ignored and a color graphics port is created.

SPECIAL CONSIDERATIONS

The GetNewDialog function doesn't release the memory occupied by the resources. Therefore, your application should mark all resources used for a dialog box as purgeable or you should release the resources yourself.

If either the dialog resource or the item list resource can't be read, the function result is nil ; your application should test to ensure that nil is not returned before performing any more operations with the dialog box or its items.

As with all other windows, dialogs are created with an update region equal to their port rectangle. However, if the dialog's 'DLOG' resource specifies that the dialog be made visible upon creation, the Dialog Manager draws the controls immediately and calls ValidRgn for each of their bounding rectangles. Other items are not drawn until the first update event for the dialog box is serviced.

If you need to display an alert box while your application is running in the background or is otherwise invisible to the user, call AEInteractWithUser ; see Inside Macintosh: Interapplication Communication.

VERSION NOTES

Changed with Appearance Manager 1.0 to support the extended dialog ('dlgx') resource and the dialog font table ('dftb') resource.

NewFeaturesDialog

Creates a dialog box from information passed in memory.



 
pascal DialogPtr NewFeaturesDialog (

                     void *inStorage,

                     const Rect *inBoundsRect,

                     ConstStr255Param inTitle,

                     Boolean inIsVisible,

                     SInt16 inProcID,

                     WindowPtr inBehind,

                     Boolean inGoAwayFlag,

                     SInt32 inRefCon,

                     Handle inItemListHandle,

                     UInt32 inFlags);

inStorage: A pointer to the memory for the dialog box. If you set this parameter to nil , the Dialog Manager automatically allocates a nonrelocatable block in your application heap.
inBoundsRect: A pointer to a rectangle, given in global coordinates, that determines the size and position of the dialog box; these coordinates specify the upper-left and lower-right corners of the dialog box.
inTitle: A pointer to a text string used for the title of a modeless or movable modal dialog box. You can specify an empty string (not nil ) for a title bar that contains no text.
inIsVisible: A flag that specifies whether the dialog box should be drawn on the screen immediately. If you set this parameter to false , the dialog box is not drawn until your application uses the Window Manager function ShowWindow to display it.
inProcID: The window definition ID for the type of dialog box, specified with constants defined by the Window Manager. Use the kWindowModalDialogProc constant to specify modal dialog boxes, the kWindowDocumentProc constant to specify modeless dialog boxes, and the kWindowMovableModalDialogProc constant to specify movable modal dialog boxes.
inBehind: A pointer to the window behind which the dialog box is to be placed on the desktop. Set this parameter to the window pointer (WindowPtr)-1L to bring the dialog box in front of all other windows.
inGoAwayFlag: A Boolean value. If true , specifies that an active modeless dialog box has a close box in its title bar.
inRefCon: A value that the Dialog Manager uses to set the refCon field of the dialog box's window structure. Your application may store any value here for any purpose. For example, your application can store a number that represents a dialog box type, or it can store a handle to a structure that maintains state information about the dialog box. You can use the Window Manager function SetWRefCon at any time to change this value in the dialog structure for a dialog box, and you can use the GetWRefCon function to determine its current value.
inItemListHandle: A handle to an item list resource for the dialog box. You can get the handle by calling the Resource Manager function GetResource to read the item list resource into memory.
inFlags: An unsigned 32-bit mask specifying the dialog box's Appearance-compliant feature flags; see Dialog Feature Flag Constants . To establish an embedding hierarchy in a dialog box, pass kDialogFlagsUseControlHierarchy in the inFlags parameter.
function result: A pointer to the newly created dialog box. If NewFeaturesDialog doesn't create a new dialog box, it returns nil .

DISCUSSION

The NewFeaturesDialog function creates a dialog box without using 'DLOG' or 'dlgx' resources. Although the inItemListHandle parameter specifies an item list ('DITL') resource for the dialog box, the corresponding dialog font table ( 'dftb' ) resource is not automatically accessed. You must explicitly set the dialog box's control font style(s) individually.

VERSION NOTES

Available with Appearance Manager 1.0 and later.